package vfs.filter;

import java.util.List;
import java.util.Map;

/**
 * The VFSFilter class represents a collection of attribute
 * constraints that can be used to filter a collection of
 * objects.
 * 
 * @author Matthew Eavenson <durandal@uga.edu>
 */
public interface VFSFilter {
    
    /**
     * The VFSFilterOperator enum represents a collection of
     * operators that can be used on a filter.
     * 
     * @author Matthew Eavenson <durandal@uga.edu>
     */
    public enum VFSFilterOperator {
        LT,         // less than
        LE,         // less than or equal to
        EQ,         // equal to
        NE,         // not equal to
        GE,         // greater than or equal to
        GT,         // greater than
        WITHIN,     // within (a range)
        NOTWITHIN,  // not within (a range)
        LIKE,       // like (string comparison)
        UNLIKE,     // unlike (string comparison)
        SORTBY      // sort by (an attribute)
    }
    
    /**
     * Sets the prefix to be used when outputting this filter
     * as a String.  In certain cases, we may need to prepend
     * operators to keep the query syntax valid, such as AND.
     * 
     * @param prefix the prefix that will be prepended to this filter
     */
    void setPrefix(String prefix);
 
    /**
     * Returns whether this filter contains any attribute constraints.
     * 
     * @return true if this filter has any attribute constraints, false otherwise
     */
    boolean hasConstraints();
    
    /**
     * Adds a collection of attribute constraints derived from a Map.
     * This method assumes that all of the attribute : value pairs
     * use the equality operator.
     * 
     * @param attrbs collection of attribute : value pairs to be added to this filter
     */
    void addConstraints(Map<String, String> attrbs);

    /**
     * Adds an attribute constraint with a specified attribute, value, and operator.
     * 
     * @param attribute the attribute to be constrained
     * @param value     the value to constrain the attribute by
     * @param op        the operator to be applied to this constraint
     */
    void addConstraint(String attribute, String value, VFSFilterOperator op);
    
    /**
     * Adds an attribute constraint with a specified attribute, lower value, and upper value
     * to return objects within the specified upper and lower values.
     * 
     * @param attribute  the attribute to be constrained
     * @param lowerValue the lower value of a range
     * @param upperValue the upper value of a range
     */
    void addWithinConstraint(String attribute, String lowerValue, String upperValue);

    /**
     * Returns a list of the constraints in effect within this filter.
     * 
     * @return a list of attribute constraints
     */
    List<VFSAttributeConstraint> getConstraints();

    /**
     * Adds an attribute constraint to this filter.
     * 
     * @param constraint the attribute constraint object to be added
     */
    void addConstraint( VFSAttributeConstraint filter );

    /**
     * Gets the current offset of this filter.  Used when paging.
     * 
     * @return the value of the offset.  -1 by default
     */
    int getOffset();

    /**
     * Sets the offset of this filter.  Used when paging.
     * 
     * @param offset the new value of the offset
     */
    void setOffset(int offset);

    /**
     * Gets the current limit of this filter.  Used when paging.
     * 
     * @return the value of the limit.  -1 by default
     */
    int getLimit();

    /**
     * Sets the limit of this filter.  Used when paging.
     * 
     * @param limit the new value of the limit
     */
    void setLimit(int limit);
    
}